home *** CD-ROM | disk | FTP | other *** search
/ IRIX Base Documentation 2002 November / SGI IRIX Base Documentation 2002 November.iso / usr / share / catman / p_man / cat3g / glob.z / glob
Encoding:
Text File  |  2002-10-03  |  18.3 KB  |  330 lines

  1.  
  2.  
  3.  
  4. gggglllloooobbbb((((3333GGGG))))                                                              gggglllloooobbbb((((3333GGGG))))
  5.  
  6.  
  7.  
  8. NNNNAAAAMMMMEEEE
  9.      _gggg_llll_oooo_bbbb - generate pathnames matching a pattern
  10.  
  11. SSSSYYYYNNNNOOOOPPPPSSSSIIIISSSS
  12.      _####_iiii_nnnn_cccc_llll_uuuu_dddd_eeee _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>>
  13.      _iiii_nnnn_tttt _gggg_llll_oooo_bbbb_((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_pppp_aaaa_tttt_tttt_eeee_rrrr_nnnn_,,,, _iiii_nnnn_tttt _ffff_llll_aaaa_gggg_ssss_,,,,
  14.          _iiii_nnnn_tttt_((((_****_eeee_rrrr_rrrr_ffff_uuuu_nnnn_cccc_))))_((((_cccc_oooo_nnnn_ssss_tttt _cccc_hhhh_aaaa_rrrr _****_eeee_pppp_aaaa_tttt_hhhh_,,,, _iiii_nnnn_tttt _eeee_eeee_rrrr_rrrr_nnnn_oooo_))))_,,,,
  15.              gggglllloooobbbb____tttt ****ppppgggglllloooobbbb))));;;;
  16.  
  17.      vvvvooooiiiidddd gggglllloooobbbbffffrrrreeeeeeee((((gggglllloooobbbb____tttt ****ppppgggglllloooobbbb))));;;;
  18.  
  19. DDDDEEEESSSSCCCCRRRRIIIIPPPPTTTTIIIIOOOONNNN
  20.      The structure type gggglllloooobbbb____tttt is defined in the header _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>> and includes
  21.      at least the following members:
  22.  
  23.      MemberType  MemberName Description
  24.      _______________________________________________________________
  25.      ssssiiiizzzzeeee____tttt      ggggllll____ooooffffffffssss    SSSSlllloooottttssss ttttoooo rrrreeeesssseeeerrrrvvvveeee aaaatttt ssssttttaaaarrrrtttt ooooffff ggggllll____ppppaaaatttthhhhvvvv....
  26.      cccchhhhaaaarrrr ********     ggggllll____ppppaaaatttthhhhvvvv   PPPPooooiiiinnnntttteeeerrrr ttttoooo lllliiiisssstttt ooooffff mmmmaaaattttcccchhhheeeedddd ppppaaaatttthhhhnnnnaaaammmmeeeessss....
  27.      ssssiiiizzzzeeee____tttt      ggggllll____ppppaaaatttthhhhcccc   CCCCoooouuuunnnntttt ooooffff ppppaaaatttthhhhssss mmmmaaaattttcccchhhheeeedddd bbbbyyyy ppppaaaatttttttteeeerrrrnnnn....
  28.  
  29.      The argument _p_a_t_t_e_r_n is a pointer to a pathname pattern to be expanded.
  30.      The _gggg_llll_oooo_bbbb function matches all accessible pathnames against this pattern
  31.      and develops a list of all pathnames that match.  In order to have access
  32.      to a pathname, _gggg_llll_oooo_bbbb requires search permission on every component of a
  33.      path except the last, and read permission on each directory of any
  34.      filename component of _p_a_t_t_e_r_n that contains any of the following
  35.      characters:
  36.  
  37.           *     ?      [
  38.  
  39.      The _gggg_llll_oooo_bbbb function stores the number of matched pathnames into
  40.      ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc and a pointer to a list of pointers to pathnames into
  41.      ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv.... The pathnames are in sort order as defined by the
  42.      current setting of the LC_COLLATE category.  The first pointer after the
  43.      last pathname is a null pointer.  If the pattern does not match any
  44.      pathnames, the returned number of matched paths is set to zero, and the
  45.      contents of ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv are undetermined.
  46.  
  47.      It is the caller's responsibility to create the structure pointed to by
  48.      _gggg_llll_oooo_bbbb.  _gggg_llll_oooo_bbbb allocates other space as needed, including the memory pointed
  49.      to by ggggllll____ppppaaaatttthhhhvvvv.... The _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee function frees any space associated with
  50.      _gggg_llll_oooo_bbbb from a previous call to _gggg_llll_oooo_bbbb.
  51.  
  52.      The _f_l_a_g_s argument is used to control the behaviour of _gggg_llll_oooo_bbbb.  The value
  53.      of _f_l_a_g_s is a bitwise inclusive OR of zero or more of the following
  54.      constants, which are defined in the header _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>>:
  55.  
  56.      _G_L_O_B__A_P_P_E_N_D
  57.  
  58.           Append pathnames generated to the ones from a previous call to _gggg_llll_oooo_bbbb.
  59.  
  60.  
  61.                                                                         PPPPaaaaggggeeee 1111
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68. gggglllloooobbbb((((3333GGGG))))                                                              gggglllloooobbbb((((3333GGGG))))
  69.  
  70.  
  71.  
  72.      _G_L_O_B__D_O_O_F_F_S
  73.  
  74.           Make use of ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss.... If this flag is set, ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss is
  75.           used to specify how many null pointers to add to the beginning of
  76.           ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv.... In other words, ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv will point to
  77.           ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss null pointers, followed by ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc pathname
  78.           pointers, followed by a null pointer.
  79.  
  80.      _G_L_O_B__E_R_R
  81.  
  82.           Causes _gggg_llll_oooo_bbbb to return when it encounters a directory that it cannot
  83.           open or read.  Ordinarily, _gggg_llll_oooo_bbbb continues to find matches.
  84.  
  85.      _G_L_O_B__M_A_R_K
  86.  
  87.           Each pathname that is a directory that matches _p_a_t_t_e_r_n has a slash
  88.           appended.
  89.  
  90.      _G_L_O_B__N_O_C_H_E_C_K
  91.  
  92.           If _p_a_t_t_e_r_n does not match any pathname, then _gggg_llll_oooo_bbbb returns a list
  93.           consisting of only _p_a_t_t_e_r_n, and the number of matched pathnames is
  94.           one (1).
  95.  
  96.      _G_L_O_B__N_O_E_S_C_A_P_E
  97.  
  98.           Disable backslash escaping.
  99.  
  100.      _G_L_O_B__N_O_S_O_R_T
  101.  
  102.           Ordinarily, _gggg_llll_oooo_bbbb sorts the matching pathnames according to the
  103.           current setting of the LC_COLLATE category.  When this flag is used
  104.           the order of pathnames returned is unspecified.
  105.  
  106.      _G_L_O_B__L_I_M_I_T
  107.  
  108.           Limit the amount of memory used by matches to {ARG_MAX} [see
  109.           sysconf(2)].  This option should be set for programs that can be
  110.           coerced to a denial of service attack via patterns that expand to a
  111.           very large number of matches.
  112.  
  113.      The GLOB_APPEND flag can be used to append a new set of pathnames to
  114.      those found in a previous call to _gggg_llll_oooo_bbbb.  The following rules apply when
  115.      two or more calls to _gggg_llll_oooo_bbbb are made with the same value of _p_g_l_o_b and
  116.      without intervening calls to _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee:
  117.  
  118.        The first such call must not set GLOB_APPEND.  All subsequent calls
  119.        must set it.
  120.  
  121.        All the calls must set GLOB_DOOFFS, or all must not set it.
  122.  
  123.        After the second call, ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv points to a list containing the
  124.  
  125.  
  126.  
  127.                                                                         PPPPaaaaggggeeee 2222
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134. gggglllloooobbbb((((3333GGGG))))                                                              gggglllloooobbbb((((3333GGGG))))
  135.  
  136.  
  137.  
  138.        following:
  139.  
  140.           Zero or more null pointers, as specified by GLOB_DOOFFS and
  141.           ppppgggglllloooobbbb---->>>>ggggllll____ooooffffffffssss....
  142.  
  143.           Pointers to the pathnames that were in the ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv list
  144.           before the call, in the same order as before.
  145.  
  146.           Pointers to the new pathnames generated by the second call, in the
  147.           specified order.
  148.  
  149.        The count returned in ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc will be the total number of
  150.        pathnames from the two calls.
  151.  
  152.        The application can change any of the fields after a call to _gggg_llll_oooo_bbbb.  If
  153.        it does, it must reset them to the original value before a subsequent
  154.        call, using the same _p_g_l_o_b value, to _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee or _gggg_llll_oooo_bbbb with the
  155.        GLOB_APPEND flag.
  156.  
  157.      If, during the search, a directory is encountered that cannot be opened
  158.      or read and _e_r_r_f_u_n_c is not a null pointer, _gggg_llll_oooo_bbbb calls (*_e_r_r_f_u_n_c()) with
  159.      two arguments:
  160.  
  161.        The _e_p_a_t_h argument is a pointer to the path that failed.
  162.  
  163.        The _e_e_r_r_n_o argument is the value of _e_r_r_n_o from that failure, as set by
  164.        _o_p_e_n_d_i_r(), _r_e_a_d_d_i_r() or _s_t_a_t().  (Other values may be used to report
  165.        other errors not explicitly documented for those functions.)
  166.  
  167.      The following constants are defined as error return values for _gggg_llll_oooo_bbbb:
  168.  
  169.      _G_L_O_B__A_B_O_R_T_E_D
  170.  
  171.           The scan was stopped because GLOB_ERR was set or (*_e_r_r_f_u_n_c())
  172.           returned non-zero.
  173.  
  174.      _G_L_O_B__N_O_M_A_T_C_H
  175.  
  176.           The pattern does not match any existing pathname, and GLOB_NOCHECK
  177.           was not set in flags.
  178.  
  179.      _G_L_O_B__N_O_S_P_A_C_E
  180.  
  181.           An attempt to allocate memory failed, or if _e_r_r_n_o was 0, GLOB_LIMIT
  182.           was specified in the flags and the amount of memory required for the
  183.           matched patterns exceeded {ARG_MAX}.
  184.  
  185.      If (*_e_r_r_f_u_n_c()) is called and returns non-zero or if the GLOB_ERR flag is
  186.      set in _f_l_a_g_s, _gggg_llll_oooo_bbbb stops the scan and returns GLOB_ABORTED after setting
  187.      _g_l__p_a_t_h_v in _p_g_l_o_b to reflect the paths already scanned.  If GLOB_ERR is
  188.      not set and either _e_r_r_f_u_n_c is a null pointer or (*_e_r_r_f_u_n_c()) returns
  189.      zero, the error is ignored.
  190.  
  191.  
  192.  
  193.                                                                         PPPPaaaaggggeeee 3333
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200. gggglllloooobbbb((((3333GGGG))))                                                              gggglllloooobbbb((((3333GGGG))))
  201.  
  202.  
  203.  
  204. RRRREEEETTTTUUUURRRRNNNN VVVVAAAALLLLUUUUEEEE
  205.      On successful completion, _gggg_llll_oooo_bbbb returns zero.  The argument
  206.      ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc returns the number of matched pathnames and the argument
  207.      ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv contains a pointer to a null-terminated list of matched
  208.      and sorted pathnames.  However, if ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc is zero, the contents
  209.      of ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv is undefined.
  210.  
  211.      The _gggg_llll_oooo_bbbb_ffff_rrrr_eeee_eeee function returns no value.
  212.  
  213.      If _gggg_llll_oooo_bbbb terminates due to an error, it returns one of the non-zero
  214.      constants defined in _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>>.  The arguments ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhcccc and
  215.      ppppgggglllloooobbbb---->>>>ggggllll____ppppaaaatttthhhhvvvv are still set as defined above.
  216.  
  217. EEEEXXXXAAAAMMMMPPPPLLLLEEEESSSS
  218.      One use of the GLOB_DOOFFS flag is by applications that build an argument
  219.      list for use with _eeee_xxxx_eeee_cccc_vvvv, _eeee_xxxx_eeee_cccc_vvvv_eeee or _eeee_xxxx_eeee_cccc_vvvv_pppp.  Suppose, for example, that an
  220.      application wants to do the equivalent of:
  221.  
  222.              _llll_ssss _----_llll _****_...._cccc
  223.  
  224.      But for some reason:
  225.  
  226.              _ssss_yyyy_ssss_tttt_eeee_mmmm_((((_""""_llll_ssss _----_llll _****_...._cccc_""""_))))
  227.  
  228.      is not acceptable.  The application could obtain approximately the same
  229.      result using the sequence:
  230.  
  231.           gggglllloooobbbbbbbbuuuuffff....ggggllll____ooooffffffffssss ==== 2222;;;;
  232.           gggglllloooobbbb ((((""""****....cccc"""",,,, GGGGLLLLOOOOBBBB____DDDDOOOOOOOOFFFFFFFFSSSS,,,, NNNNUUUULLLLLLLL,,,, &&&&gggglllloooobbbbbbbbuuuuffff))));;;;
  233.           gggglllloooobbbbbbbbuuuuffff....ggggllll____ppppaaaatttthhhhvvvv[[[[0000]]]] ====""""llllssss"""";;;;
  234.           gggglllloooobbbbbbbbuuuuffff....ggggllll____ppppaaaatttthhhhvvvv[[[[1111]]]] ====""""----llll"""";;;;
  235.           eeeexxxxeeeeccccpppp ((((""""llllssss"""",,,, &&&&gggglllloooobbbbbbbbuuuuffff....ggggllll____ppppaaaatttthhhhvvvv[[[[0000]]]]))));;;;
  236.  
  237.      Using the same example:
  238.  
  239.              _llll_ssss _----_llll _****_...._cccc _****_...._hhhh
  240.  
  241.      could be approximately simulated using GLOB_APPEND as follows:
  242.  
  243.           gggglllloooobbbbbbbbuuuuffff....ggggllll____ooooffffffffssss ==== 2222;;;;
  244.           gggglllloooobbbb ((((""""****....cccc"""",,,, GGGGLLLLOOOOBBBB____DDDDOOOOOOOOFFFFFFFFSSSS,,,, NNNNUUUULLLLLLLL,,,, &&&&gggglllloooobbbbbbbbuuuuffff))));;;;
  245.           gggglllloooobbbb ((((""""****....hhhh"""",,,, GGGGLLLLOOOOBBBB____DDDDOOOOOOOOFFFFFFFFSSSS||||GGGGLLLLOOOOBBBB____AAAAPPPPPPPPEEEENNNNDDDD,,,, NNNNUUUULLLLLLLL,,,, &&&&gggglllloooobbbbbbbbuuuuffff))));;;;
  246.            ...
  247.  
  248. AAAAPPPPPPPPLLLLIIIICCCCAAAATTTTIIIIOOOONNNN UUUUSSSSAAAAGGGGEEEE
  249.      This function is not provided for the purpose of enabling utilities to
  250.      perform pathname expansion on their arguments, as the operation is
  251.      performed by the shell, and utilities are explicitly not expected to redo
  252.      this.  Instead, it is provided for applications that need to do pathname
  253.      expansion on strings obtained from other sources, such as a pattern typed
  254.      by a user or read from a file.
  255.  
  256.  
  257.  
  258.  
  259.                                                                         PPPPaaaaggggeeee 4444
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266. gggglllloooobbbb((((3333GGGG))))                                                              gggglllloooobbbb((((3333GGGG))))
  267.  
  268.  
  269.  
  270.      If a utility needs to see if a pathname matches a given pattern, it can
  271.      use _ffff_nnnn_mmmm_aaaa_tttt_cccc_hhhh.
  272.  
  273.      Note that ggggllll____ppppaaaatttthhhhcccc and ggggllll____ppppaaaatttthhhhvvvv have meaning even if _gggg_llll_oooo_bbbb fails.  This
  274.      allows _gggg_llll_oooo_bbbb to report partial results in the event of an error.  However,
  275.      if ggggllll____ppppaaaatttthhhhcccc is zero, ggggllll____ppppaaaatttthhhhvvvv is unspecified even if _gggg_llll_oooo_bbbb did not return
  276.      an error.
  277.  
  278.      The GLOB_NOCHECK option could be used when an application wants to expand
  279.      a pathname if wildcards are specified, but wants to treat the pattern as
  280.      just a string otherwise.  The _ssss_hhhh utility might use this for option-
  281.      arguments, for example.
  282.  
  283.      The new pathnames generated by a subsequent call with GLOB_APPEND are not
  284.      sorted together with the previous pathnames.  This mirrors the way that
  285.      the sheel handles pathname expansion when multiple expansions are done on
  286.      a command line.
  287.  
  288.      Applications that need tilde and parameter expansion should use _wwww_oooo_rrrr_dddd_eeee_xxxx_pppp.
  289.  
  290. SSSSEEEEEEEE AAAALLLLSSSSOOOO
  291.      execv(2), fnmatch(3g), opendir(3b), readdir(3b), stat(2), wordexp(3g),
  292.      _<<<<_gggg_llll_oooo_bbbb_...._hhhh_>>>>.
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.                                                                         PPPPaaaaggggeeee 5555
  326.  
  327.  
  328.  
  329.